home *** CD-ROM | disk | FTP | other *** search
/ Mac Format 1996 April / MacFormat CD Edition MF36 (April 1996).iso / Shareware City / Developers / Tools Plus - GUI⁄Event libs / Tools Plus 2.6.1a Evaluat'n Kit / Tools Plus 2.6.1a / User Manual / Update History / Read Me! 2.1 -> 2.5 changes < prev    next >
Text File  |  1994-09-11  |  15KB  |  289 lines
  1. Tools Plus Changes: 2.1 to 2.5
  2. ~~~~~~~~~~~~~~~~~~~~~~~
  3. Display this document in Geneva 12pt.
  4.  
  5. You need to read this document if:
  6.    √ You are upgrading from an older version of Tools Plus. If you
  7.        are upgrading from a version older than 2.5, read all other
  8.        applicable change documents first.
  9.  
  10.  
  11.                                       * * * W A R N I N G * * *
  12.  
  13.           THIS UPDATE INCLUDES REVISIONS THAT MAY REQUIRE YOU
  14.           TO CHANGE PARTS OF YOUR EXISTING APPLICATION(S). 
  15.           PLEASE READ CAREFULLY.
  16.  
  17.  
  18. Tools Plus 2.5, released in June 1994, includes the following changes implimented since the previous version, 2.1:
  19.  
  20.   • Tools Plus 2.5 contains a new set of libraries and files.  Replace
  21.      your existing Tools Plus files with the new ones included in this
  22.      update.
  23.          Note that Tools Plus has been expanded to three libraries
  24.      from the original two, and that all three must be used as a set.
  25.      Delete all your old copies of the Tools Plus libraries and related
  26.      files (C header, Pascal interface etc.)
  27.  
  28.   • A tool bar and floating palettes (windoids) are now supported.
  29.      They are as easy to create and maintain as a standard Tools Plus
  30.      window.  (Read important notes in this document!)
  31.  
  32.   • Picture Buttons are now supported, letting you transform any
  33.      icon or picture into a multi-functional button.  You can duplicate
  34.      the functionality of standard push buttons, check boxes, radio
  35.      buttons, and go far beyond.  You specify the button’s behavior and
  36.      appearance.
  37.  
  38.   • Pop-Up menus are now supported, offering more features than the
  39.      Mac toolbox’s implementation of Pop-Up menus.
  40.  
  41.   • Hierarchical menus are now supported, plus some new routines
  42.      have been added to facilitate menu handling.  Icon handling has
  43.      been enhanced beyond the Macintosh toolbox’s services.
  44.  
  45.   • Buttons can now be displayed using multiple fonts and styles
  46.  
  47.   • Integrated access to the Mac toolbox’s Notification Manager
  48.  
  49.   • Cursor Zones can now be defined as regions in addition to the
  50.      previously available rectangles.
  51.  
  52.   • Your application’s ‘SIZE’ resource now needs to have both the
  53.      “Accept suspend events” and “Does activate on FG switch” bits
  54.      set to 1.  In prior version’s, these settings were optional.
  55.  
  56.   • Cursor Animation has been enhanced to animate any cursor
  57.      sequence.  Several cursor sequences have been included as
  58.      samples (they’re in the “Optional Resources” folder)
  59.  
  60.   • A new “Beep” routine has been added
  61.  
  62.   • Tools Plus’s “SystemTasks” routine is now obsolete and has been
  63.      deleted.  Its function is integrated into PollSystem.
  64.  
  65.   • Tools Plus’s “SetCursDragBounds” routine is now obsolete and
  66.      has been deleted.  Its function is integrated into PollSystem.
  67.  
  68.   • Improved processor sharing (new SetNullTime and WaitAvail
  69.      routines have been added)
  70.  
  71.   • Constants are now available to facilitate placing scroll bars on
  72.      the right edge or bottom edge of a document’s window.
  73.  
  74.   • Each window’s update region is “protected” to exclude Tools
  75.      Plus’s objects, so your application can refresh a window’s
  76.      contents without concern about overwriting buttons, scroll bars,
  77.      editing fields, etc.
  78.  
  79.   • The DrawIcon routine has been revised to respect Color
  80.      QuickDraw conventions: a ‘cicn’ icon can be displayed on a
  81.      monitor set to 4-bits.  DrawIcon can now draw _any_ icon on any
  82.      supported system version, and observes appearance options set
  83.      by your application.
  84.  
  85.   • The doClick event now populates the Poll.Event field with the
  86.      mouse-down event (as obtained from the toolbox Event Manager)
  87.      that is responsible for the doClick event.  Some applications need
  88.      this event to drive custom controls.
  89.  
  90.   • ToolsPlus.h header file (THINK C only) now uses “shorts” instead
  91.      of “ints”, thereby allowing the “4-byte integers” compiler option
  92.      to be used.
  93.  
  94.   • The InsertMenuItem routine has been renamed to InsertMenuitem
  95.      (with a lower case “i” in item) to maintain compatibility with
  96.      THINK C 7’s libraries.  This affects C programmers only, since
  97.      Pascal is not case-sensitive.
  98.  
  99.   • ToolsPlus.p interface file (THINK Pascal only) now uses integers
  100.      instead of typed variables for parameters to Tools Plus routines.
  101.      Tools Plus still performs automatic range checking.
  102.  
  103.   • Code optimization (portions of Tools Plus were rewritten to
  104.      make it quicker and more memory-efficient).
  105.  
  106.   • Tools Plus’s color drawing routines are now aware of System
  107.      Extensions like “Now Menus”, which can change monitor settings
  108.      without any indication to applications.
  109.  
  110.  
  111.  
  112.  
  113.  
  114.  
  115. Tool Bar and Palettes
  116. ~~~~~~~~~~~~~~~~~
  117.   Tools Plus now supports a tool bar and multiple floating palettes.  If your application uses either of these, you will have to learn a few additional concepts, specifically, that your application can now have multiple _active_ windows (the frontmost standard window, plus a tool bar and all palettes).
  118.   If your applications do not have a tool bar or floating palettes, Tools Plus routines will continue to function as expected.  When you take advantage of the additional power of tool bars and/or floating palettes, you will need to know about the new information which can be found in the following chapters:
  119.   • Windows (new tool bar and palette window types, new routines).
  120.      Windows can now be moved (WindowMove), resized (WindowSize),
  121.      and hidden (WindowDisplay).
  122.   • Buttons (no default button on tool bar or palettes).  FlashButton
  123.      tries to find the specified button on the working window first,
  124.      then the front most standard window.
  125.   • Editing Fields (the application’s active editing field can be
  126.      located on any active window, which now includes the tool bar
  127.      and floating palettes).
  128.   • System Polling (some existing Tools Plus events are generated in
  129.      response to activity in the tool bar and palettes).
  130.  
  131. IMPORTANT: Significant changes have been made in the handling of windows.  Please re-read the chapters listed above.
  132.  
  133.   The TPWindowStatus record (used by the WindowStatus routine) has been expanded to provide more information about the window being queried.  It is no longer field-compatible with the old version.
  134.  
  135.   The Mac toolbox’s FrontWindow routine becomes less useful now that the front most window can be a tool bar or any of the floating palettes (instead of the front most standard window).  Fortunately, Tools Plus provides routines to determine the front most floating palette, and front most standard window.
  136.  
  137.  
  138.  
  139.  
  140.  
  141. Picture Buttons
  142. ~~~~~~~~~~~~
  143.   Picture Buttons let you transform any icon or picture into a multi-functional button.  You can duplicate the functionality of the standard Macintosh buttons (push buttons, check boxes, radio buttons), or go further and customize the button’s behavior and appearance.
  144.   Color 3D icons can be created from simple, black and white icons.  Tools Plus calculates the shading and highlighting to make the buttons appear to stand out from the window, and to be pushed in when selected by the user.
  145.   Multiple behavioral options are available, along with selection effects and disabling effects.
  146.  
  147.  
  148.  
  149.  
  150.  
  151. Pop-Up Menus
  152. ~~~~~~~~~~~
  153.   Pop-Up menus are now supported, as detailed in the “Pop-Up Menus” section of the manual.  Tools Plus’s Pop-Up menus offer more power and versatility than System-7’s Pop-Up menus, plus they are available to all System versions.
  154.  
  155.  
  156.  
  157.  
  158.  
  159. Menus and Hierarchical Menus
  160. ~~~~~~~~~~~~~~~~~~~~~~~
  161.   Hierarchical menus are now supported.  The Menu routine has been extended to create and rename hierarchical menus as well as the standard pull-down menus, while the new AttachMenu routine is used to attach and detach submenus.
  162.   Menus can now display ‘SICN’ icons for Macintoshes that need small (16x16 pixels) icons and don’t have Color QuickDraw.
  163.   The “Menus” section of the manual has been rewritten to include new hierarchical menu information.
  164.  
  165.  
  166.  
  167.  
  168.  
  169. Buttons with Multiple Styles
  170. ~~~~~~~~~~~~~~~~~~~~~~
  171.   In version 2.1, each window could display buttons in one of two possible “styles”: (1) the System Font (Chicago 12pt), or (2) one other application-defined font/size/style.
  172.   When a button is created in version 2.5, the window’s current font, size and style settings (as set by the TextFont, TextSize, and TextFace procedures) are remembered by the button.  The window’s settings can then be changed without affecting the button.  Unlike ordinary buttons, Tools Plus buttons can each have a different font.
  173.  
  174.  
  175.  
  176.  
  177.  
  178. Cursor Zones as “Regions”
  179. ~~~~~~~~~~~~~~~~~~~~
  180.   Cursor Zones (areas where the cursor automatically changes to a different shape) were only available as rectangles under version 2.1 or older.  In version 2.5, Cursor Zones can be created as regions, in addition to the previously available rectangles.
  181.   All previous cursor routines are still available.  In addition, the following new cursor routines are available in version 2.5:
  182.      CursorZoneRgn         (create/change a Cursor Zone specifying a
  183.                                      region)
  184.      GetCursorZoneRgn    (get a region handle to a Cursor Zone)
  185.      ChangedCursorZone  (indicate that a cursor zone’s region has
  186.                                      been manually altered)
  187.  
  188.  
  189.  
  190.  
  191.  
  192. Notification Manager Integration
  193. ~~~~~~~~~~~~~~~~~~~~~~~~~~
  194.   Applications running under System 6 or higher now have integrated access to the Notification Manager.  Dynamic Alerts automatically make use of the Notification Manager if they are called while your application is inactive.
  195.   The following new routines are available in version 2.5:
  196.      SetNotification        (specify how the user should be notified)
  197.      PostNotification      (notify the user)
  198.  
  199.  
  200.  
  201.  
  202.  
  203. Positioning Scroll Bars on Edge of Documents
  204. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  205.   Tools Plus 2.5 includes constants that facilitate placing a scroll bar along the right edge or bottom edge of a sizeable document window.  If you use these constants instead of actual co-ordinates, Tools Plus will correctly position the scroll bar.
  206.  
  207.   If you use the following constants, Tools Plus will place the scroll bar along the right edge of the window:
  208.          left       scrlRightEdge
  209.          top        scrlTopEdge   (optional)
  210.          right     scrlRightEdge
  211.          bottom  scrlBottomEdge
  212.  
  213.   If you use the following constants, Tools Plus will place the scroll bar along the bottom edge of the window:
  214.          left       scrlLeftEdge   (optional)
  215.          top        scrlBottomEdge
  216.          right     scrlRightEdge
  217.          bottom  scrlBottomEdge
  218.  
  219.   CONST                              {Scroll bar state                                 }
  220.     enabled             =true;    {enable the scroll bar                         }
  221.     disabled            =false;  {disable the scroll bar                        }
  222.     scrlLeftEdge     =-1;       {SCROLL BARS: left edge of document }
  223.     scrlTopEdge      =-1;       {             top edge of document           }
  224.     scrlRightEdge   =32767; {             right edge of document         }
  225.     scrlBottomEdge=32767; {             bottom edge of document      }
  226.  
  227.  
  228.  
  229.  
  230.  
  231. New Beep routine
  232. ~~~~~~~~~~~~~
  233.   Beep replaces the Macintosh toolbox’s SysBeep routine.  On the Macintosh 512KE, Plus and SE, the parameter passed to the SysBeep routine specifies the duration (in clock ticks) for which the “Simple Beep” sound is played.  If any other sound is selected (by the Sound control Panel), or if the sound is played on a computer other than the Macintosh 512KE, Plus and SE, the parameter is ignored.
  234.   Using Beep instead of SysBeep ensures that the System Error sound is played for the correct duration regardless of the computer on which it is running.  It also saves you typing, as well as two bytes per instance.
  235.  
  236.  
  237.  
  238.  
  239.  
  240. Improved Processor Sharing
  241. ~~~~~~~~~~~~~~~~~~~~~~
  242.   Applications written with Tools Plus 2.5 can improve the performance of other applications and processes that are running at the same time.  If no event was available for your application in prior versions of Tools Plus, your application received doNothing events every time it called PollSystem.  This used up processing time even if your application did nothing other than call PollSystem in its main event loop.
  243.  
  244.   In version 2.5, your application can set the interval between receiving doNothing events.  If your application must perform on-going tasks while waiting for events, it can schedule doNothing events to occur twenty or thirty times a second.  Other applications that need to perform a process periodically, may schedule doNothing events once a minute.  If your application does no background processing, it can schedule an infinite time between doNothing events.
  245.  
  246.   Regardless of the scheduling of doNothing events, PollSystem still lets your application receive events as soon as they are available.
  247.  
  248. Also see:  SetNullTime and WaitAvail
  249.  
  250. Note: The SIZE resource’s “Can Background” bit now has a
  251.          recommended setting of “1.”  If your application does no
  252.          background processing, schedule doNothing events to occur at
  253.          an infinite interval.
  254.  
  255.  
  256.  
  257.  
  258.  
  259. Protected Update Region
  260. ~~~~~~~~~~~~~~~~~~~
  261.   When your application receives a doRefresh event for a window, it responds with a BeginUpdate/EndUpdate block, which redraws the window’s contents.  In Tools Plus 2.5, the call to BeginUpdate now modifies the window’s update region (that’s where drawing occurs) to exclude Tools Plus’s objects (buttons, scroll bars, editing fields, list boxes, and custom controls).  This allows your application to refresh the window’s contents without concern for overwriting any of Tools Plus’s objects.
  262.  
  263.  
  264.  
  265.  
  266.  
  267. DrawIcon revision
  268. ~~~~~~~~~~~~~~
  269. When a monitor is set to 4-bits, DrawIcon still prefers an ‘icl4’ icon.  If one is not available, it now tries to use a ‘cicn’ icon even though the ‘cicn’ icon may have been created using 8-bit colors.  This is consistent with Color QuickDraw conventions.
  270.   DrawIcon can now draw any icon, regardless of system version.  This means that a ‘cicn’ icon can be drawn on a Macintosh without Color QuickDraw.
  271.   Your application can now specify a different look for icons that are selected and/or disabled.  See the DefaultIconLook routine for details.
  272.   A bug fix has been made that now correctly calculates a ‘cicn’ icon’s mask when the ‘cicn’ icon is not the standard 32x32 pixel size.
  273.  
  274.  
  275.  
  276.  
  277.  
  278. ToolsPlus.h: “shorts” instead of “ints”
  279. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  280.   In the ToolsPlus.h header file (C programmers only), all the “int” variables have been redeclared as “short”.  This is because Tools Plus requires 2-byte variables that are equivalent to Pascal’s integers, and using shorts in place of ints allows C programmers to use the optional “4-byte ints” compiler settings.
  281.  
  282.  
  283.  
  284.  
  285.  
  286. ToolsPlus.p: “integers” instead of “typed parameters”
  287. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  288.   In the ToolsPlus.p interface file (Pascal programmers only), all the typed variables used for parameters to Tools Plus routines have been redeclared as integers.  Tools Plus’s full-time range checking is more effective in a stand-alone application using this strategy.
  289.